Tic-Tac-Toe over Sockets for Series 40
======================================

Tic-Tac-Toe Over Sockets port for Series 40 touch and type and full touch
devices. This Nokia example demonstrates the use of datagrams for peer 
discovery and the use of TCP sockets for peer-to-peer communication. 

This example application demonstrates:
- The use of datagrams to implement automatic peer discovery
- How to use TCP sockets for peer-to-peer communication
- How to scale graphics for varying size of game board

This example application is hosted in Nokia Developer Projects:
- http://projects.developer.nokia.com/s40tictactoe

For more information on implementation and porting, visit the wiki pages:
- http://projects.developer.nokia.com/s40tictactoe/wiki


1. Usage
-------------------------------------------------------------------------------

To play with two devices, make sure that the devices are connected to the same
wireless network and that the reception is good. Then launch the application and
tap "Start Two Player Game". The devices should discover each other. Once the
connection is established, the game board is shown and the game begins.

Note that the discovery is not guaranteed to work in all networks. The automatic
peer discovery works only with the condition that the wireless access point
hands out IP addresses where the last digit varies. E.g. the discovery will work
with devices that have IPs 111.111.111.10 and 111.111.111.20, but not if the IPs
are 111.111.10.0 and 111.111.20.0.


2. Project structure and implementation
-------------------------------------------------------------------------------

2.1 Folders
-----------

 |                  The root folder contains the project files, the Application
 |                  Descriptor file, the license information and this file
 |                  (release notes).
 |
 |- binaries        Contains the installable binaries.
 |
 |- res             Contains the application resources (e.g. graphics assets).
 |
 |- src             Contains the application source code.

2.2 Important files and classes
-------------------------------

Note that some files/classes are omitted from the following tree.

 src/ com.nokia.example.tictactoe
 |- Main.java...........................The MIDlet main class.
 |- Splash.java.........................The splash screen implementation.
 |
 |- com.nokia.example.tictactoe.connectivity
 |  |- Connection.java..................An abstract class defining a base for
 |  |                                   any connection.
 |  |- ConnectionManager.java...........Provides the main API for managing
 |  |                                   the whole package. However, the
 |  |                                   individual connection classes can be
 |  |                                   used separately.
 |  |- DiscoveryClient.java.............UDP client based peer discovery
 |  |                                   connection.
 |  |- DiscoveryServer.java.............UDP server based peer discovery
 |  |                                   connection.
 |  |- TcpClient.java...................TCP client socket connection.
 |  |- TcpServer.java...................TCP server socket connection.
 |  |- UdpClient.java...................UDP (datagram) client socket connection.
 |  |- UdpServer.java...................UDP (datagram) server socket connection.
 |
 |- com.nokia.example.tictactoe.console
 |  |- Console.java.....................Displays the log messages on the screen.
 |  |- Log.java.........................Container for log messages.
 |  |- TextWrapper.java.................A utility class for wrapping text when
 |                                      drawn with Graphics.drawString().
 |- com.nokia.example.tictactoe.engine
 |  |- AbstractGameManager.java.........An abstract base class for game
 |  |                                   managers.
 |  |- BasicGameManager.java............A game manager for single player game.
 |  |- GameModel.java...................The game model which knows where
 |  |                                   everything is.
 |  |- IGameModelListener.java..........An interface for game model listeners.
 |  |- ITicTacToeAI.java................An interface for any AI (articial
 |  |                                   intelligence) opponent implementation.
 |  |- MinimaxAI.java...................A simple minimax algorithm based AI
 |  |                                   implementation.
 |  |- NetworkGameManager.java..........A game manager for two player game.
 |
 |- com.nokia.example.tictactoe.ui
 |  |- AboutView.java...................The about/info view.
 |  |- Button.java......................A custom button.
 |  |- GameGrid.java....................The visualisation of the game board.
 |  |- GameView.java....................The game view.
 |  |- InfoLabel.java...................A custom text label with a background.
 |  |- ITouchListener.java..............An interface for touch event listeners.
 |  |- MainView.java....................The main (menu) view.
 |  |- ProgressBar.java.................A custom progress bar.
 |  |- SettingsView.java................The settings view.
 |  |- TextLabel.java...................A custom text label.
 |  |- TimedProgressBar.java............A progress bar with a timer.


2.3 Used J2ME and Nokia UI API classes
--------------------------------------

Note: Some, less meaningful packages and classes omitted.

- java.io
  - InputStream
  - OutputStream

- javax.microedition.io
  - Connector
  - Datagram
  - DatagramConnection
  - ServerSocketConnection
  - SocketConnection
  
- javax.microedition.lcdui
  - Canvas
  - Display
  - Displayable
  - Font
  - Graphics
  - Image


3. Compatibility
-------------------------------------------------------------------------------

Compatible with Series 40 touch and type and full touch phones. Developed with
Nokia SDK 2.0 for Java.

3.1 Known issues
----------------

- The game does not function well, if the reception of the wireless network is
  poor, and connectivity implementation is not generally very tolerant for
  network errors.
- The automatic peer discovery feature is not guaranteed to work in all
  wireless networks; the implementation depends on the wireless access point to
  hand out IPs where only the last value in the IP varies.


4. Building, installing, and running the application
-------------------------------------------------------------------------------

4.1 Preparations
----------------

Check that you have Nokia SDK 2.0 for Java (or equivalent SDK) and the latest
Nokia Suite installed.

4.2 Packaging the application using Nokia SDK 2.0 for Java
----------------------------------------------------------

You cannot install the application on the device with the IDE, but you can 
package the application: after you have imported the project, locate the
Application Descriptor in the Package Explorer window and open it. Open the 
Overview tab (by default it is the first tab on the left) and click Create
package. Select the destination directory and click Finish.

4.3 Installing application binary with Nokia Suite
--------------------------------------------------

Connect the phone to the computer with USB cable or Bluetooth. Locate the
application binary (.jar file). Open the file using Nokia Suite. You can also
drag the file from the file explorer on top of the connected phone image in the
Nokia Suite window.

After the application is installed, locate the application icon from the
application menu and launch the application by selecting the icon.


5. License
-------------------------------------------------------------------------------

See the license text file delivered with this project. The license file is also
available online at
http://projects.developer.nokia.com/s40tictactoe/browser/trunk/License.txt


6. Version history
-------------------------------------------------------------------------------

1.0 Initial release
